跳到主要内容

通用选项说明

该模块在 20260507 以后版本方可使用

多个 ui_element 接口接受选项表,用于指定目标 App、返回数量、递归深度、命中验证和滚动步进。

查询选项​

local options = {
pid = app.front_pid(),
max_level = 2,
max_elements = 200,
include_hit_state = true,
}
  • pid
    整数型,指定目标 App 的进程标识符。不传时通常使用前台 App。
  • max_level
    整数型,子元素递归深度。常用 1 或 2 控制返回数据量。
  • max_elements
    整数型,最多返回的顶层元素数量。
  • fallback_children
    布尔型,普通列表为空时尝试读取子元素。默认值随接口不同而不同。
  • include_hit_state
    布尔型,是否补充命中状态字段。
  • hit_test
    布尔型,是否启用屏幕采样命中。普通脚本通常不需要开启。
  • fallback_hit_test
    布尔型,普通列表为空时是否尝试屏幕采样命中。
  • hit_test_spacing
    数值型,屏幕采样间距,单位为逻辑坐标。默认 40。

属性排除选项​

20261115 起可用。仅用于 snapshot() 和 list_text_elements();均为布尔型,默认 false,对子元素同样生效。不需要相应状态时,启用这些排除选项可减少查询开销,加快快照抓取。

  • exclude_visibility
    为 true 时跳过可见性查询,省略 isVisible。
  • exclude_map
    为 true 时跳过地图属性判断,省略 isMap,保留地图元素。
  • exclude_hit_state
    为 true 时跳过中心点命中检查,省略 canHit、hitVerified、hitTestPoint 和 hitTestPointLogical;不能与 include_hit_state = true 同时使用。

元素范围、文字和坐标保持不变,hit_test / fallback_hit_test 的补抓规则不变。需要按这些状态筛选时,不要排除相应字段。

动作选项​

  • point
    表型,指定滚动或命中使用的坐标点,例如 { x = 200, y = 700 },单位为物理像素。
  • x / y
    整数型,和 point 等价,可直接放在选项表中。
  • steps
    数值型,用于滚动、增加或减少操作的步进参数。具体效果取决于目标控件。

说明​

list_text_elements() 为兼容旧脚本,默认更保守。 find()、find_all()、snapshot() 和动作类接口更适合新脚本直接使用。 hit_test 可能返回更接近当前顶层界面的元素,但成本更高,建议只在普通查询拿不到元素时使用。